Description

This PR transitions the holodeck documentation build process from a static, error-prone manual setup to an automated, programmatic pipeline. This work resolves longstanding build warnings, cleans up stale documentation artifacts, and ensures the API reference is always in sync with the source code.

Key Changes:

• Build Automation:
  • Introduced docs/generate_api_ref.py and updated docs/docgen.sh to handle API reference generation programmatically.
  • Removed over a dozen manually tracked rst files from docs/source/api_ref and added the directory to .gitignore, reducing clutter.
• Documentation Parsing:
  • Enabled sphinx.ext.napoleon in docs/source/conf.py to improve support for existing docstrings. (numpydocs is broken in Python 3.12).
  • Extensive refactoring of docstrings in single_sources.py, hardening.py, and detstats.py to resolve build-time parsing errors.
• Efficiency & Reproducibility:
  • Decoupled documentation from heavy runtime dependencies (like sympy, healpy, and hasasia) by implementing autodoc_mock_imports in conf.py.
  • Cleaned up toctree hierarchy and consolidated biblio.rst and index.rst references to ensure a clean, warning-free build.

Testing Verification (Clean-Clone Build):

To ensure reproducibility and functionality, this PR was verified with a fresh repository clone. The following steps confirmed a successful build:

git clone https://github.com/nanograv/holodeck.git
git switch dev-documentation
micromamba env create -f environment.yml
micromamba activate holopy
cd docs/
pip install -r requirements.txt
cd ../
./docs/docgen.sh

AI Use Statement

This documentation refactor and the accompanying automation scripts were developed with the assistance of Google Gemini Flash-Lite 3.1. The LLM was operated in a way such that it could not directly modify code or run any commands (i.e., I used Gemini web app and asked questions, pasted code fragments, uploaded error statements, etc.). Essentially, the LLM acted as a pair-programmer, assisting with debugging Sphinx configuration, refactoring legacy docstring formats, and refining this PR description.

Documentation can still be improved!

This PR is about improving the documentation build and the automation of existing documentation, not on the actual content of the documentation. Documentation can always be improved!

Impact

• Build Status: The documentation now builds with zero errors or warnings.
• Maintenance: API reference updates are fully automated; manual editing of generated rst files is no longer required.

(Note: The large volume of deletions in the PR is intentional, representing the removal of legacy, pre-generated API reference files in favor of the new dynamic generation pipeline.)

Status

• Ready to go